Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 4 - Dialog Manager Reference / Dialog Manager Functions

Handling Events in Dialog Boxes /

ModalDialog

CHANGED WITH THE APPEARANCE MANAGER

Handles events while your application displays a modal or movable modal dialog box.

pascal void ModalDialog (
                     ModalFilterUPP modalFilter,
                     short *itemHit);

modalFilter

A universal procedure pointer for an event filter function. For modal dialog boxes, you can specify nil if you want to use the standard event-handling function. For movable modal dialog boxes, you should specify your own event filter function.

itemHit

A pointer to a short integer. After receiving an event involving an enabled item, ModalDialog produces a number representing the position of the selected item in the active dialog box's item list resource.

DISCUSSION

Call the ModalDialog function immediately after displaying a modal or movable modal dialog box. Your application should continue calling ModalDialog until the user dismisses your dialog.

For modal dialogs, the ModalDialog function repeatedly handles events until an event involving an enabled dialog box item--such as a click in a radio button, for example--occurs. If the event is a mouse-down event outside the content region of the dialog box, ModalDialog plays the system alert sound and gets the next event.

For movable modal dialogs, if the kDialogFlagsHandleMovableModal feature bit in the extended dialog resource is set, the ModalDialog function will handle all standard movable modal user interactions, such as dragging a dialog box by its title bar and allowing the user to switch into another application. However, a difference between the ModalDialog function's behavior with movable modal and modal dialogs is that, with movable modal dialogs, your event filter function receives all events. If you want the Dialog Manager to assist you in handling events in movable modal dialog boxes, call GetStdFilterProc and StdFilterProc.

For events inside the dialog box, ModalDialog passes the event to the event filter function pointed to in the modalFilter parameter before handling the event. When the event filter returns false, ModalDialog handles the event. If the event filter function handles the event, returning true, ModalDialog performs no more event handling.

If you set the modalFilter parameter to nil, the standard event filter function is executed. The standard event filter function checks whether

• the user has pressed the Enter or Return key and, if so, returns the item number of the default button
• the user has pressed the Escape key or Command-period and, if so, returns the item number of the Cancel button
• the cursor is over an editable text box, and optionally changes the cursor to an I-beam whenever this is the case

If you set the modalFilter parameter to point to your own event filter function, that function can use the standard filter function to accomplish the above tasks. (To do so, you can call GetStdFilterProc, and dispatch the event to the standard filter function yourself, or you can call StdFilterProc , which obtains a ModalFilterUPP for the standard filter function and then dispatches the function.) Additionally, your own event filter function should also

• handle update events, so that background processes can receive processor time, and return false
• return false for all events that your event filter function doesn't handle

You can also use your event filter function to test for and respond to keyboard equivalents and more complex events--for instance, the user dragging the cursor within an application-defined item. You can use your same event filter function in most or all of your alert and modal dialog boxes.

If the event filter function does not handle the event (returning false), ModalDialog handles the event as follows:

• In response to an activate or update event for the dialog box, ModalDialog activates or updates its window.
• If the user presses the mouse button while the cursor is in an editable text item, ModalDialog responds to the mouse activity as appropriate--that is, either by displaying an insertion point or by selecting text. If a key-down event occurs and there's an editable text item, ModalDialog uses TextEdit to handle text entry and editing automatically. If the editable text item is enabled, ModalDialog produces its item number after it receives either the mouse-down or key-down event. Normally, editable text items are disabled, and you use the GetDialogItemText function to read the information in the items only after the user clicks the OK button.
• If the user presses the mouse button while the cursor is in a control, ModalDialog calls the Control Manager function TrackControl. If the user releases the mouse button while the cursor is in an enabled control, ModalDialog produces the control's item number. Your application should respond appropriately--for example, by performing a command after the user clicks the OK button.
• If the user presses the mouse button while the cursor is in any other enabled item in the dialog box, ModalDialog produces the item's number, and your application should respond appropriately. Generally, only controls should be enabled. If your application creates a control more complex than a button, radio button, or checkbox, your application must handle events inside that item with your event filter function.
• If the user presses the mouse button while the cursor is in a disabled item or in no item, or if any other event occurs, ModalDialog does nothing.

SPECIAL CONSIDERATIONS

The ModalDialog function traps all events. This prevents your event loop from receiving activate events for your windows. Thus, if one of your application's windows is active when you use GetNewDialog to create a modal dialog box, you must explicitly deactivate that window before displaying the modal dialog box.

When ModalDialog calls the Control Manager function TrackControl, it does not allow you to specify the action function necessary for anything more complex than a button, radio button, or checkbox. If you need a more complex control, you can create your own control, a picture, or an application-defined item that draws a control-like object in your dialog box. You must then provide an event filter function that appropriately handles events in that item.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

ModalDialog only handles events for modal dialogs.